Summary

Adds the Sandbox primitive to the agents runtime — a pluggable abstraction that isolates the filesystem, process, and network operations performed by LLM-driven tool calls — and wires it end-to-end through the runtime, agents-server, desktop, and new-session UI.

The primitive

@electric-ax/agents-runtime/sandbox exposes a deliberately small Sandbox interface: exec, FS methods (readFile/writeFile/mkdir/readdir/exists/remove/stat), fetch (egresses through the sandbox's own network), and dispose. SandboxError carries a policy | runtime | unavailable kind. Containment is documented per concern rather than promised uniformly — writes contained on every provider; reads contained on unrestricted/docker; in-workspace symlink escapes rejected on unrestricted. name is a free-form provider id for logs, not a capability discriminator.

Providers

• unrestrictedSandbox — in-process pass-through over node:fs / child_process; the built-in default. A single-tenant, trusted-code default: the tool layer contains reads/writes to the workspace and rejects symlink escapes, but it shares the host FS/PID namespace and is not a containment boundary.
• dockerSandbox — hardened container isolation via dockerode (optional peer dep): CapDrop ALL, no-new-privileges, no docker socket, pids/mem/cpu limits. deny-all ⇒ NetworkMode=none (the hard network boundary); any other policy gets a bridge, where the allowlist + SSRF guard are fetch-tool-only surface protection, not an exec/bash egress boundary. Exported under /sandbox/docker so callers needing only unrestricted don't pull dockerode.
• remoteSandbox({provider: 'e2b'}) — first-class adapter for E2B's npm SDK (optional peer dep): reattaches to a shared workspace by key and defers lifecycle to the platform (see below). The RemoteSandboxClient interface makes adding Vercel/Daytona/etc. mechanical.

An earlier iteration shipped a nativeSandbox provider (Seatbelt/bubblewrap via @anthropic-ai/sandbox-runtime). It was removed in favour of Docker as the hardened-isolation path; the dependency is gone.

Lifecycle & identity

resolveSandboxIdentity derives three orthogonal facts from an entity's sandbox config + the live wake:

• Identity — an explicit cross-entity key, or a scope shorthand ('entity' default ⇒ entityUrl; 'wake' ⇒ entityUrl#wakeId for full per-wake isolation). "Full isolation" is just a unique key, never a separate code path.
• Durability (persistent) — selects the owner's idle teardown: preserve (stop/suspend, reattachable) vs wipe (remove/kill).
• Ownership (owner) — an owner creates and governs teardown; a non-owner (an inherit spawn) only attaches to an already-live sandbox and never conjures a fresh one.

Per-key locked, refcounted, debounced teardown with deterministic container/workspace naming so a cold-started host reattaches by key. processWake constructs the sandbox once per wake-session and disposes it in the outer finally (handlers must not call dispose()).

Sandbox profiles (advertise / validate / pick)

• Runtimes register named SandboxProfiles (name, label, description?, remote?, local factory). Built-ins: local (always), docker (only when the Docker daemon is reachable), and e2b (only when E2B_API_KEY is set and the optional e2b dep is installed) — so the UI never offers a non-functional choice.
• The runtime advertises the descriptive fields (not the factory closures) to the agents-server via runner registration. New migration 0010_sandbox_profiles adds runners.sandbox_profiles and entities.sandbox.
• Spawn requests carry the sandbox selection; the server validates the chosen profile against the target runner's advertised set (or, for unpinned dispatch, a tenant-wide check) and rejects unserviceable choices up front.
• The new-session UI reads the selected runner's advertised profiles and renders a picker; the sidebar surfaces per-session runner/sandbox badges and can group sessions by runner.

E2B remote provider — shareable, persistent, desktop-ready

remoteSandbox({provider: 'e2b'}) is a first-class shareable provider, mirroring how the Docker provider handles shared/persistent containers:

• Reattach by key. A shared sandbox is tagged with sandboxKey (e2b metadata); a wake looks it up via list + connect (which auto-resumes a paused VM) and only creates one when none is alive — so collaborators and later wakes, even on a freshly cold-started host, converge on the same workspace. A cross-host create race resolves deterministically (oldest wins). Private (per-entity) sandboxes are created fresh per wake.
• Platform-deferred lifecycle. Shared sandboxes are created with lifecycle: { onTimeout: 'pause' } and kept alive by a setTimeout heartbeat while a wake holds them (e2b's timeout is absolute, not idle, so activity doesn't refresh it). dispose() just stops the heartbeat — the platform auto-suspends the VM on idle (filesystem + memory preserved, reattachable for e2b's paused-retention window) with no explicit teardown and no cross-host refcount. Private sandboxes still kill() on dispose.
• Co-location guard relaxed for remote. A per-profile remote flag flows runtime → runner advertisement → server. A shared local sandbox still requires its collaborators to be pinned to a single runner (the container lives on one host); a shared remote sandbox is reachable from any runner, so the single-runner guard is skipped for it.
• Desktop. The Electron app offers the e2b profile gated on an E2B_API_KEY credential (stored alongside the Anthropic/OpenAI/Brave keys and mirrored into the runtime env on save), and externalizes the optional e2b dep from the Electron main bundle. The new-session picker keeps an explicit profile choice across runner re-advertisement and hides the working-directory control for remote profiles. Horton reports and reads AGENTS.md from the sandbox's own working directory (/work in the VM) rather than a host path, so the model never sees paths its tools can't reach.

Tool refactor + hardening (folded in)

• All tool factories (createFetchUrlTool, read/write/edit, bash) now require a Sandbox parameter and route through it.
• bash no longer forwards process.env to children — removes the trivial env-dump leak of secrets like $ANTHROPIC_API_KEY. (The host-sharing unrestricted provider still can't fully contain secrets, e.g. via /proc/<ppid>/environ; use docker/remote for untrusted or multi-tenant entities.)
• read/write/edit reject symlink escapes from the workspace — enforced in the sandbox (unrestricted.resolveWithin, the CVE-2025-53109/53110-shape defense) and surfaced through the tools.
• docker exec polls inspect() until the exec is reaped, so a cleanly-exited command never returns a transient null exit code.
• the boot orphan sweep (sweepOrphanedDockerSandboxes) reclaims only exited ephemeral leftovers — it never force-removes a running container (possible live sibling on a shared daemon) or a persistent one (meant to be reattached by key).
• the docker fetch SSRF guard canonicalizes encoded IP literals (decimal/hex integer, ::ffff:-mapped, bracketed IPv6) so they can't bypass the private/link-local/metadata check.

Built-in entities (Horton, Worker) default to unrestrictedSandbox via chooseDefaultSandbox(workingDirectory). Stronger isolation is opt-in by selecting the docker/e2b profile or constructing dockerSandbox / remoteSandbox directly.

What this primitive is and is not

Targets host isolation for LLM-driven tool calls (cwd escape, env-var exfil, arbitrary network egress, symlink traversal). It does not address prompt-injection-driven misuse of otherwise-legitimate tools.

Provider-specific limitations (documented in the interface, not promised uniformly):

• unrestrictedSandbox is not a containment boundary — it shares the host FS/PID namespace. Tool-layer policy (workspace + symlink containment, host-env scrubbing) shrinks the blast radius but does not stop host-level reads (e.g. /proc) or SSRF from fetch_url.
• docker only hard-enforces deny-all (NetworkMode=none) and allow-all; allowlist is enforced host-side at the fetch tool only, and code run via exec/bash has direct bridge egress.
• sandbox.fetch() on remoteSandbox runs an HTTP client inside the VM via exec, so egress is governed by the VM's network controls.
• e2b shared sandboxes assume sequential collaboration (parent → subagent): the provider offers no cross-host coordination, and pausing disconnects any other live client.

Test plan

• Cross-provider conformance suite pins the Sandbox contract across unrestricted / remote (in-memory fake of the RemoteSandboxClient SDK contract) / docker (gated on daemon availability).

• Per-provider suites: docker lifecycle + keyed reattach + scoped orphan sweep (running/persistent preserved, exited-ephemeral reclaimed); unrestricted containment + tool-layer symlink safety; net-policy SSRF incl. encoded-literal canonicalization; profiles; tool-refactor.

• E2B (mock-based, no live account in CI): reattach-by-key, keep-alive heartbeat, suspend-vs-kill dispose — sandbox-remote.test.ts.

• Server-side spawn validation (electric-agents-sandbox-spawn.test.ts) incl. a shared remote profile bypassing the single-runner guard while a shared local one still requires pinning; runners-router.test.ts round-trips the remote flag.

• Verified locally: agents-runtime (724 tests) + agents-server + agents suites green; all packages typecheck clean; docker integration suite (incl. new exec-reap + scoped-sweep tests) green against a live daemon.

• CI matrix exercises the Docker path on Linux

• Manual smoke test of remoteSandbox({provider: 'e2b'}) against a real E2B account (verified on desktop: shared sandbox resolves to remote:e2b at /work, reattaches across wakes)

🤖 Generated with Claude Code